I think we should have another option added to this site that refers to Tutorials.. maybe a clone of News and then have nothing but tutorials in there...

It is hard right now finding tutorials in the forums or news articles.

Anyhow I will try to write a tutorial here for upgrades.... Please provide feedback so we can try to build a good tutorial to give to new users upgrading from old versions of Xoops.

Maybe we can make this a sticky to help out new users since the system to upgrade will not change much...

So you have been handed a site that has Xoops 2.0.x, 2.1, 2.2 or whatever.

Before you attempt an upgrade you will want to do some research before hand.

As of this writing the latest stable version is 2.5.4 with 2.5.5 beta on the table and 2.6 in pre-alpha. There have been a lot of changes from the 2.0 series to today and they require that you do some homework before upgrading to help make the change over as seamless as possible.

You will need to do three things before you get ready to do an actual upgrade to your live site.

Make a full backup of your system's database and files before you attempt anything. If you fail to do this portion you could end up loosing the whole site and you really should be backing up your system pretty often anyhow.

Install a copy of your site on a local computer for testing purposes. This will require some changes to your mainfile.php but should be relatively painless. You should attempt all upgrades on this local copy before trying on your main server. again you want to prevent issues on your live site. It is best that you try to use a local server that is as close to the server you are using or are going to use. (Linux, MS, etc.)

Create an inventory of the modules in your system and their versions. You will want to decide which modules you want to keep and which ones you will upgrade later. The idea here is the fewer modules you have to upgrade the fewer chances for mistakes. The older the xoops you are running the more of a chance of there being issues here. This is why we backup and use a local server to test out on.. If it works to upgrade locally it will work to upgrade on your live host.

You will also need a way to access your database directly. MOST systems support something PHPMyAdmin and you should be somewhat familiar with this as you will need to use it.

Lastly, you will want to figure out what version of Xoops you want to upgrade to.

2.3.3, I believe was the first version that was built for php 5. Not sure if it is worth upgrading to this version. Since most modern hosts run php 5 now you will want to upgrade to this version at a minimum. This might make sense if you are running an old system and can't get it working with a newer xoops. This version was intended to bring the best of 2.0, 2.1 and 2.2 together.

2.4.5, My understanding was that this was essentially 2.3.3 with a major facelift mostly for admins. Because of the similarity between the core of this and 2.3.3 there really isn't a real good reason to use 2.3.3. The interface and the security upgrade are well worth the upgrade. This version is the most stable of the current xoops at this time. So if you are upgrading from an old system I STRONGLY suggest at a minimum to start with this version.

2.5.4, The latest version of xoops at the time of this writing. If you can upgrade to this version it is the best version to date but is most likely to break your old modules. 2.5.5 beta is available as well. The only modules truly certified to work with 2.5 series are in the basic module pack. Since this is an evolving version you may want to try out the modules you want to use with this and make sure it works. This should also be the most secure version of Xoops today. At this point this series is where you want to be but you may find yourself sticking with 2.4.5 if the issues are too many to warrant upgrading to the 2.5 series just yet.

Now that you have backed up your system, installed a copy on a local computer and figured out what modules you want to keep and upgrade and which ones you can do without it is time to upgrade.

If you are upgrading from a version older than the 2.3 series you will really want to make sure you disable all of the modules on your system that you can before you do the upgrade. This is a good idea any time you are upgrading from an older version to a newer version. If it is the same series you can likely get away with not doing this but it is a good idea to do regardless. I am not sure but I don't think the upgrade script normally disables modules.. Regardless, you should disable all of your modules during the duration of the upgrade as it will make this simpler.

You will also want to look through the database entries and figure out where to disable and enable modules for the version of xoops you are installing. When you have your system installed you may need to manually be able to enable and disable modules as you debug your system. So it is a good idea to figure this out before hand.

Remove any add ons, modules or other items you no longer need. With us turning off the current modules we are preserving the data in them so we can convert to a different module or keep them in place to upgrade to a newer module version.

You will want to disable the site and then remove any files in the cache directories and delete any entries in the session tables. The upgrade script may do this but to be sure it is done you can do this yourself.

Again make sure you do all of this on a local version of your site so you do not destroy your live site.


Follow the directions to upgrade to the version of Xoops you are doing. When you are done with the upgrade you will want to log into your system and physically run the "update" for the system module. Test out that the site is working before you do anything else. When dealing with the live site you do NOT want to enable it before you are fully back up and running. But since you are working on your local version this should not be a big issue...

I will stop here for now and add more when I get home from work. If you got this far however and everything is working you are well on your way to a working site with the latest version of xoops.

Good idea Rodney! In a final version of this tutorial you better compact text, as there is too many to read now. A numbered step by step approach would also help to make the tutorial more clear, and are you using xoops version x jump to step x added.

I'd go with videotutorials. Made a first step with that a while back, but never really finished it.

part 1 : http://www.youtube.com/watch?v=dLKhAv8JV0s
part 2 : http://www.youtube.com/watch?v=FrLVYWU9Ddc

Mmm, I like video tutorials to get an impression, but never would use them aside when doing an upgrade. I prefer a tutorial in print/ on paper, for me that's the only way to do an upgrade properly, without forgetting nescesarry steps.

I agree, yes going back and reading this it is a bit wordy... And I am not done yet...

But hopefully good information can be shared and a good tutorial come out of it that can help someone figure out what to do etc..

Hopefully if I am successful with some future projects any such tutorial will not be necessary.

Rodney, in every Core release we provide links to detailed Installation Guide and Operations Guide.

There are also "Upgrade" instructions as part of the Installation Guide.

Feel free to rewrite this part or create a new one, so we could include it back into the Installation Guide.

The same is for other documents. If anybody can take the time and improve an existing document, or create a new one from scratch, please do so, and we'll include it with the next release.

I didn't realize that document also talks about upgrades... Just looked it over real quick. Will have to look it over further before making further comments on that or this thread. However it would be nice if tutorials and such were easier to find than just posting a message and hoping someone can help you out.

Quote:
The link to this documentation is included in every Core release.

But sure, we can always make it more visible.