Warning: This page has not been updated in over over a year and may be outdated or deprecated.
videos:upgrading_vufind_using_git
Differences
This shows you the differences between two versions of the page.
| Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
| videos:upgrading_vufind_using_git [2023/04/25 20:09] – [Transcript] crhallberg | videos:upgrading_vufind_using_git [2023/04/26 13:30] (current) – [Transcript] crhallberg | ||
|---|---|---|---|
| Line 14: | Line 14: | ||
| ===== Transcript ===== | ===== Transcript ===== | ||
| - | With the recent release of VuFind™ 7.0, I thought now would be a good time to share my upgrade workflow to show how I use Git to upgrade VuFind™. This video is going to assume that you have a basic familiarity with Git, and if you do not, I strongly, strongly recommend learning at least the basics. Doing software development and deployment without version control is like driving without a seatbelt, and you will find that investing a little time in learning these tools will save you all kinds of trouble down the road. | + | With the recent release of VuFind 7.0, I thought now would be a good time to share my upgrade workflow to show how I use Git to upgrade VuFind. This video is going to assume that you have a basic familiarity with Git, and if you do not, I strongly, strongly recommend learning at least the basics. Doing software development and deployment without version control is like driving without a seatbelt, and you will find that investing a little time in learning these tools will save you all kinds of trouble down the road. |
| - | So this video will cover two basic topics. The first will be turning an existing installation of VuFind™ into a Git repository so that you can use Git to manage it, and the second part will show some processes and tools for using Git to perform actual upgrades. | + | So this video will cover two basic topics. The first will be turning an existing installation of VuFind into a Git repository so that you can use Git to manage it, and the second part will show some processes and tools for using Git to perform actual upgrades. |
| - | So the virtual machine I've been using for this series of tutorials was initially set up by installing VuFind™ from the Debian package, which just puts the files on disk but does not include any kind of version control. We are going to take advantage of a useful characteristic of Git, namely that all of the version control data is stored in a dot Git subdirectory, | + | So the virtual machine I've been using for this series of tutorials was initially set up by installing VuFind from the Debian package, which just puts the files on disk but does not include any kind of version control. We are going to take advantage of a useful characteristic of Git, namely that all of the version control data is stored in a dot Git subdirectory, |
| - | But before we can begin doing all of that, the most important thing we need to do first is figure out exactly which version of VuFind™ we are already running, because that will enable us to put Git into the correct state to start all of the work that we need to do. There are a couple of ways to identify which version of VuFind™ you're running. A simple one, particularly useful if you don't have access to the server running VuFind™, is to simply view the page source while looking at any VuFind™ webpage, and look for the generator meta tag, which should have a version number embedded in it, so we can see here 6.1.1. However, the generator meta tag is not 100% reliable, because it's actually created based on a config.ini setting, and if that configuration file gets out of date or is customized, it's possible that what it's reporting is not actually the truth. If you want to be more confident that you have the right number, you should go to the command line, switch to your VuFind™ home directory, and edit the build.xml file. This is the control file used by the Thing Automation | + | But before we can begin doing all of that, the most important thing we need to do first is figure out exactly which version of VuFind we are already running, because that will enable us to put Git into the correct state to start all of the work that we need to do. There are a couple of ways to identify which version of VuFind you're running. A simple one, particularly useful if you don't have access to the server running VuFind, is to simply view the page source while looking at any VuFind webpage, and look for the generator meta tag, which should have a version number embedded in it, so we can see here 6.1.1. However, the generator meta tag is not 100% reliable, because it's actually created based on a config.ini setting, and if that configuration file gets out of date or is customized, it's possible that what it's reporting is not actually the truth. If you want to be more confident that you have the right number, you should go to the command line, switch to your VuFind home directory, and edit the build.xml file. This is the control file used by the phing automation |
| - | Now that we know what version we're running, as I said, we can start creating a Git repository to turn this bare file collection into a tracked version controlled repository. And before I begin, I'm just going to confirm if I run a Git status from my VuFind™ home, it tells me it's not a Git repository. So let's go get one. | + | Now that we know what version we're running, as I said, we can start creating a Git repository to turn this bare file collection into a tracked version controlled repository. And before I begin, I'm just going to confirm if I run a Git status from my VuFind home, it tells me it's not a Git repository. So let's go get one. |
| If we go to the temp directory, we can run git clone https github.com/ | If we go to the temp directory, we can run git clone https github.com/ | ||
| Line 30: | Line 30: | ||
| This is why it's important to be disciplined about separating your localizations from the core. And one of the advantages of using Git is that it helps you to do this because if you accidentally change a core file that will show up when you do a Git status and then you'll know oh I shouldn' | This is why it's important to be disciplined about separating your localizations from the core. And one of the advantages of using Git is that it helps you to do this because if you accidentally change a core file that will show up when you do a Git status and then you'll know oh I shouldn' | ||
| - | In any case once you're comfortable that you understand your local customizations in their scope the next thing I highly recommend doing is looking at the change log in the VuFind™ wiki and I will link to this from the video recording. But for every release of VuFind™ we include notes not only on new features that might be of interest but also of changes to code and configuration that could potentially cause problems during an upgrade. We are very inclusive here because we want to catch every possible issue that might be a problem. Most of these are unlikely to affect most users but that's why it's helpful to have a broad idea of what you've customized because you can then read through this list and take note of which issues are likely to be a problem and which ones you can very safely ignore. | + | In any case once you're comfortable that you understand your local customizations in their scope the next thing I highly recommend doing is looking at the change log in the VuFind wiki and I will link to this from the video recording. But for every release of VuFind we include notes not only on new features that might be of interest but also of changes to code and configuration that could potentially cause problems during an upgrade. We are very inclusive here because we want to catch every possible issue that might be a problem. Most of these are unlikely to affect most users but that's why it's helpful to have a broad idea of what you've customized because you can then read through this list and take note of which issues are likely to be a problem and which ones you can very safely ignore. |
| - | In the case of this specific upgrade that we are about to run the one change log note that I need to be concerned about is this one. Starting with VuFind™ 7 we changed the default port that Solr runs on from 8080 to 8983. This is because 8983 is the standard port number used by Solr and using 8080 historically has caused port conflicts with other applications. It seems to make sense to standardize that but now at upgrade time we need to be aware of this change so that we can deal with it appropriately. Right now our Solr is running on port 8080 and after the upgrade VuFind™ will be looking for it on port 8983. I'll show you how to deal with that after the rest of the process and of course this particular issue only applies to VuFind™ 7 but this is just an example of the kind of thing you should be aware of when you're reviewing the change log. | + | In the case of this specific upgrade that we are about to run the one change log note that I need to be concerned about is this one. Starting with VuFind 7 we changed the default port that Solr runs on from 8080 to 8983. This is because 8983 is the standard port number used by Solr and using 8080 historically has caused port conflicts with other applications. It seems to make sense to standardize that but now at upgrade time we need to be aware of this change so that we can deal with it appropriately. Right now our Solr is running on port 8080 and after the upgrade VuFind will be looking for it on port 8983. I'll show you how to deal with that after the rest of the process and of course this particular issue only applies to VuFind 7 but this is just an example of the kind of thing you should be aware of when you're reviewing the change log. |
| Finally the third thing that you should always do before attempting an upgrade is back everything up and of course it's best to test an upgrade on a non-production server before you dive in in the real world. In this instance I'm not going to show you how I backed things up because this is a virtual machine and I've just backed up the whole disk image before I started so I can roll back if I have to but whatever your situation just be sure that you have a rollback plan so if something goes wrong during upgrade you haven' | Finally the third thing that you should always do before attempting an upgrade is back everything up and of course it's best to test an upgrade on a non-production server before you dive in in the real world. In this instance I'm not going to show you how I backed things up because this is a virtual machine and I've just backed up the whole disk image before I started so I can roll back if I have to but whatever your situation just be sure that you have a rollback plan so if something goes wrong during upgrade you haven' | ||
| - | With all that background out of the way we're just about ready to begin. There' | + | With all that background out of the way we're just about ready to begin. There' |
| We changed the Solr ownership because the user running the Solr process needs to be able to write there but what we can do is work around this with a group ownership. I will leave Solr owned by Solr but I'm going to add it to the dkatz group which will give my user account permission to update files in that directory and I'm going to do that with the '' | We changed the Solr ownership because the user running the Solr process needs to be able to write there but what we can do is work around this with a group ownership. I will leave Solr owned by Solr but I'm going to add it to the dkatz group which will give my user account permission to update files in that directory and I'm going to do that with the '' | ||
| Line 72: | Line 72: | ||
| Right now, I'm just going to move quickly past the rest of config.ini. And now I've reached my import settings where the only change is related to the solar port number change once again. And this is so that the mark import tool knows where to find solar. So we have two files with that port number changing. We have some new examples added to our mark local dot properties. Again, it's all just comments, so it won't hurt anything, but it brings our local version up to date in case we want to turn this on in the future. And finally, a little bit of adjustment to our local custom theme to reflect some style changes that were made to the core and which have been automatically applied correctly here thanks to the merge script. | Right now, I'm just going to move quickly past the rest of config.ini. And now I've reached my import settings where the only change is related to the solar port number change once again. And this is so that the mark import tool knows where to find solar. So we have two files with that port number changing. We have some new examples added to our mark local dot properties. Again, it's all just comments, so it won't hurt anything, but it brings our local version up to date in case we want to turn this on in the future. And finally, a little bit of adjustment to our local custom theme to reflect some style changes that were made to the core and which have been automatically applied correctly here thanks to the merge script. | ||
| - | So that's it, our VuFind™ is now fully upgraded. We just have one last thing to deal with, which is the issue I raised earlier of the change solar port number. Because right now, we haven' | + | So that's it, our VuFind is now fully upgraded. We just have one last thing to deal with, which is the issue I raised earlier of the change solar port number. Because right now, we haven' |
| - | So VuFind™ has now stopped, but we are going to need to make one small adjustment to the system deconfiguration because the port number is embedded in the PID file that VuFind™ uses to keep track of running processes. So we need to tell systemd that this 8080 dot PID has changed to an 8983 PID. And because we made a change to a systemd file, we need to say pseudo systemctl demon reload to make sure that the latest version of that is already. And then we can start the VuFind™ service once again. | + | So VuFind has now stopped, but we are going to need to make one small adjustment to the system deconfiguration because the port number is embedded in the PID file that VuFind uses to keep track of running processes. So we need to tell systemd that this 8080 dot PID has changed to an 8983 PID. And because we made a change to a systemd file, we need to say pseudo systemctl demon reload to make sure that the latest version of that is already. And then we can start the VuFind service once again. |
| There' | There' | ||
| - | And now, if all has gone smoothly, I should be able to refresh my VuFind™ homepage. And if I view the source of it, I see that my generator now says 7.0 instead of 6.1.1. That's a good sign. And let's perform a search and confirm that yes, the whole thing still works. We are now upgraded to VuFind™ 7.0. | + | And now, if all has gone smoothly, I should be able to refresh my VuFind homepage. And if I view the source of it, I see that my generator now says 7.0 instead of 6.1.1. That's a good sign. And let's perform a search and confirm that yes, the whole thing still works. We are now upgraded to VuFind 7.0. |
| - | So just to summarize, upgrading VuFind™ with git. It's not an easy process. It requires an understanding of your local system and configuration. It requires some problem solving and resolving conflicts. It's always good to have backups before you attempt to tackle it. But as you become familiar with the tools of git and the supplemental merge script, it does automate the vast majority of the work for you and draws your attention to key areas that might require additional work. So I hope this demonstration has been of some help and will help you form useful habits to keep up to date on VuFind™ in the future. And as always, if you have problems or questions, please reach out to me directly or to the VuFind™ mailing lists, and I'll be happy to help. Thank you for your time. | + | So just to summarize, upgrading VuFind with git. It's not an easy process. It requires an understanding of your local system and configuration. It requires some problem solving and resolving conflicts. It's always good to have backups before you attempt to tackle it. But as you become familiar with the tools of git and the supplemental merge script, it does automate the vast majority of the work for you and draws your attention to key areas that might require additional work. So I hope this demonstration has been of some help and will help you form useful habits to keep up to date on VuFind in the future. And as always, if you have problems or questions, please reach out to me directly or to the VuFind mailing lists, and I'll be happy to help. Thank you for your time. |
| //This is an edited version of an automated transcript. Apologies for any errors.// | //This is an edited version of an automated transcript. Apologies for any errors.// | ||
videos/upgrading_vufind_using_git.1682453340.txt.gz · Last modified: 2023/04/25 20:09 by crhallberg