Here’s a quick, generic guide on how to upgrade Mystic BBS from one version to another. I’m presenting this both because I’ve seen the occasional new Mystic SysOp ask for guidance on upgrading, but also because my BBS, Distortion, had been lagging behind several versions for a while, and the latest version as of this writing, 1.12 A43, seems to be fairly stable, so I figured it was time for me to upgrade. If my efforts can serve as a real-world demonstration of the upgrade process for others, why not? Note that this guide is definitely aimed at Mystic newbies, so if you’ve been at it for a while, you probably won’t get too much out of this.
While I’m demoing the process under Windows, it’s fundamentally the same for other builds of Mystic.
Process Overview:
• First and foremost, backup your BBS. This can be done as simply as making a copy of your Mystic directory. Having this pre-upgrade backup available will allow you to “roll back” your changes if something should go wrong, or you encounter issues with the new version after the upgrade.
• Next you need to download the version you intend on going to. While the latest version is listed prominently on http://www.mysticbbs.com, all of the older alpha versions of the current release and some much, much older files are also available at http://www.mysticbbs.com/downloads/.
• Open upgrade.txt from the archive you just downloaded in your text editor of choice. Keep it open, as you’ll be referencing it a lot.
• Scroll down to the section entitled “UPGRADING FROM xxx to xxx” for the version you’re currently running. In my case, Distortion was running 1.12 A38, so I’d be looking at the instructions titled “UPGRADING FROM 1.12 A37/A38 to A39”.
Read ALL of these instructions!
• Many releases will only require replacing executables and sometimes recompiling your MPL scripts, but some involve many other steps. You should reference the whatsnew.txt file from the archive you downloaded earlier to get a better idea of what each of the required steps is referring to. You may be able to skip some steps related to features you’re not using, or you may need other information not listed in upgrade.txt.
Tip: In my opinion it’s much more convenient to reference the “what’s new” information from the Mystic Wiki, as it lists all of the changes for the entire version in an easier to read and search format, as well as linking to earlier version information too. http://wiki.mysticbbs.com/doku.php?id=whats_new_112 is the v1.12 what’s new, for instance.
• If you’re upgrading through multiple versions in your upgrade, you should next scroll up to the next section. This would be “UPGRADING FROM 1.12 A39 to A40” for me, for example. Repeat the process of reading the upgrade instructions for this version and referencing the whatsnew.txt for that version if necessary. You should repeat this process until you get to the version you intend on moving to.
The purpose of doing this is to look for potential opportunities to avoid unnecessary, repeated tasks. You can often skip multiple steps, making a few changes as needed and then copying the executables from a later version, or even “leap over” versions entirely, saving yourself a lot of work. If you feel like there are too many changes and you’re paranoid about missing something, it may be safest just to follow each set of individual upgrade instructions one at a time.
In my case, I’ll be mostly following each section of version upgrade instructions one at a time.
• If you’re able to leap to your intended version or you are only upgrading one version, you can begin the process. Otherwise, download the version you need to start with. For me, this would be 1.12 A39.
I’d recommend shutting down your BBS before actually going through the upgrade steps, as it’s possible you could accidentally corrupt some of your data files or produce various other errors, and that’s no fun!
• I HIGHLY recommend reading whatsnew.txt in full for details on what’s been added or changed in the new version(s) you’re upgrading to, even if you’ve already read it when referencing changes. Upgrade.txt only includes the bare minimum steps required to upgrade to the new version and leaves out details on the vast majority of new features and enhancements. Whatsnew.txt is more or less the only source for documentation these days, so you’ll want to make sure you don’t miss out on anything new you might benefit from implementing. More importantly, it’s nice to know why things are suddenly working different in a new version, right?
• After the upgrade is finish (and perhaps between versions, if going step by step) you should test your system, looking for any issues. Assuming none pop up, you’re done!
Maybe take one more skim through whatsnew.txt to consider the impact of some of the new changes as well as how you might implement some of the new features. Yes, I know I might be overselling this, but I suppose I have a lot of guilt about rarely taking advantage of James’s hard work with Distortion. 😉
Next in part 2, the fun part! We’ll go through my actual upgrade process…