Update Status

The upgrade of the site involves a long list of steps to perform. This wiki page will be a working document of those steps, listed in order of execution.

Acquire new HW

The site needs new HW so a dedicated system is required. Let's defer the decision now about what kind of system it is, or even where it is located (dedicated metal, cloud-based, etc..) those are not technically important at this phase. But what is required is new HW (modern, capable and on a network backbone that is sufficient for the amount and rate of data movement to end-users).

Apply Packages to the System

The baseline assumption is that the new system runs Linux, I will insist on that. To make the commercial site software execute, the system requires a few packages to be installed. That list has been identified and is in another page (TBD link) here.

Data Transfer Process

In order to make the site upgrade appear seamless to the user (no loss of thread continuity), the existing site must be shutdown for about 10-14 days.

When the site is shutdown to the users, the next steps are as follows:

A SQL Dump

The command to make a SQL dump of the database is performed. Instructions for that step are documented on this Wiki. (TBD Link to that page)

A Copy of Files

The file-system (aka DocumentRoot) of the site needs to be copied. The technique to do this efficiently has already been documented on this Wiki. (TBD Link to that page)

Acquire Updated Software

The new commercial software drop has been acquired. We have the license and the .zip file for the updated software.

The Upgrade

1. In empty document root on the new site, unpack the legacy file system files.
2. Edit conf_global.php to configure the new-site values for the database user and password. (see preexisting Wiki page on this, URL TODO)
3. Load the legacy SQL database into the new hardware. The page to do that has already been written on this Wiki (Link to page TODO)
4. On top of the legacy files, unpack the contents of the update software

The recommendation at this point is to run the UTF-8 conversion script in the command-line and NOT in the web interface:

From the shell, perform this step:

$ cd DOC_ROOT/admin/convertutf8
$ /usr/bin/screen -dmS FIX php -f cli.php

That will run the script to convert, but it will want user intervention immediately, so re-attach the screen:

$ screen -r

And the question you see is to start, enter y

You can leave the screen attached and let it run. It'll take about 1-2 days of constant execution to finish. Leave the screen attached so you can monitor for errors or intervention. The process should be self-contained and run to conclusion and then exist on its own.

Proceed with upgrade

Now it's possible to resume the upgrade:

Visit the URL http://yourdomain/admin/upgrade

Be prepared to enter the EMAIL address of an Admin account -- this is the Admin user of the LEGACY system. Be prepared to enter the PASSWORD of that Admin account -- this is the Admin user of the LEGACY system. Be prepared to enter the LICENSE key of the NEW software. Remember: do not "burn up" the license for the production server. The license key to enter must be appended with the string -TESTINSTALL So for example if the License Key was ABC-123, the key to enter will be:

ABC-123-TESTINSTALL

You must add the hyphen between the Key and the word TESTINSTALL

Questions

The process will run through a set of pages and sequences for the Admin to continue the Upgrade.

Along the way it will ask for some preferences for what kind of upgrade to make.

The question of note will be whether or not to convert "Friends" to "Followers". Choose Yes (convert). Make Friends become Followers. If we don't then the "Friends" associated with existing Users will be lost. It's a minor semantic change, and the Users will prefer it rather than losing all context of who are following them.

Manual SQL

During the upgrade, the web page that orchestrates the actions taken will prompt the admin to run SQL statements on the database.

Recommendation: Do so manually in mysql, there is no better option.

Before setting up to run the manual SQL statements, decide what kind of editor you want to use.

There are options.

• vi (aka vim)
• pico (a cursor control based editor)

And others..

I you don't know vi (vim) then don't use it, it's not for novices. Use nano or pico if you want a nice friendly cursor based editor.

BEFORE running mysql do this:

$ export EDITOR=pico

or

$ export EDITOR=nano`

or

$ export EDITOR=vi`

depending on what kind of editor you want to use.

Then,

1. Start up mysql

$ mysql -u user -D database_name -p

For user the user will be given to you by the admin. For database_name the database name will be given to you by the admin.

This will result in a mysql> prompt

2. From there, you can enter the manual SQL statements.

mysql> edit

3. To test your chops using mysql with the editor, do this:

mysql> edit

Then in the editor type in:

select 'this is a test';

Close the editor. press ENTER

In MySQL ; terminates a SQL statement.

Compare to:

mysql> edit

Enter this SQL Statement:

select 'this is a test'

(without the trailing ;)

Then close the editor (saving) Then type in ; followed by pressing ENTER

The result is you should see

+----------------+
| this is a test |
+----------------+
| this is a test |
+----------------+
1 row in set (0.00 sec)

That just proves you can enter SQL statements and invoke them.

Some of the SQL statements you'll need to make will take several seconds to run. No anxiety -- let it run until completion. When you see the mysql> prompt again, you'll know it's done. Look for error messages. If there are error messages, repair the problem and re-run the SQL statement you started with before confirming that the statement ran w/o error.

4. Enter the requested SQL statement per the web page, verbatim!

• Paste the SQL Statement
• Save the file you're in (the editor will actually be editing a temporary file), just close the editor saving the change with whatever name it is using. Do not try to re-save the file under a different name. Just whatever the key-chord is to "save and exit" is, use it.
• The prompted SQL statement to enter will likely have the terminating ; on the end of the statement. So when you have saved-and-exited the editor and press ENTER it should run. If not do this: Type in ; Press ENTER
• Then wait.
• MySQL will report how many rows were affected. It's OK if 0 rows were affected. Action will still have taken place that is appropriate.

If you need help resolving errors generated by the SQL statement, seek the Admin for help. Do not proceed with errors. Do not ignore errors.

Bugs

Then the Upgrade continues per the Software process, but there will be errors that occur due to the database having bad values in one or more tables.

I've already discovered those errors and have written the simple SQL to fix those errors so that the Upgrade can continue (TODO: Put link to those SQL statements already written)

TBD

The process will continue and when more is known, this page will be updated.