User:Aeric/Create a New Branch

You branch the Wiki to create a sandbox for the next generation of edits.

1 Process Overview

The process is this:

Copy the existing database to a new one (wiki{next_version}. Ex: wiki81)
Install a new version of the wiki at /{newWiki}
Adjust the settings to point to the new database.
Make a few other adjustments.

Note: The installation step is necessary. It pre-configures many paths that are based on the installation directory--paths that are difficult to track down and reconfigure later.

2 Requirements

An ftp app like FileZilla client
A text editor like Notepad++
An editor you're comfortable using over an SSH connection (vi, in a pinch). Nano is installed on Rackspace, and works reasonably.
Access to the internet to get the latest version of MediaWiki
A merge program to incorporate edits to LocalSettings.php
- TortoiseMerge (comes with TSV, works great)
- WinMerge (free)
7-zip to unzip .tar.gz files to local PC
Adobe Illustrator to modify the logo
An icon-file editor to modify the bookmark/tab/address-bar icon. (See Rename the Wiki.)

3 Prep Images

It is important for the images in the new version to have different names. Pointing to files with different names keeps browsers from displaying cached versions of the files, with the old version numbers, when the redirect "/wiki" is loading a page from the same source. (In some browsers, it is impossible to update the images--especially the "favicons"--even when doing a full reload of the page. It seems that they do not query the dates of such image files.)

Note: As an alternative, we could keep the same names, and add ?{version_number} to the URLs. Most browsers will assume dynamic behavior, and won't cache the images. That would ensure the new images are loaded, but since they wouldn't be cached, they would be fetched from the server for every page!

To prep the images:

Go to the SVN-controlled directory C:\Relationals\techpubs\images\logos
Edit the LJ_Logo_Versioned.ai file with Adobe Illustrator.
- Change the version number.
- Save the file.
- Export to LJ_Logo_{new_version}.png
  Ex: LJ_Logo_81.png
- Resolution: Screen (72 ppi).

- Background: Transparent.
Create the .ico icon file (32x32, 4 color)
- Copy longjump_{old_version}.ico to longjump_{new_version}.ico
  Ex: longjump_81.ico
- Use IcoFX
- Delete existing
- Click "T" icon (text), and click in the Icon area:
Font: Stencil if available, else Stencil Standard, Normal (not bold)

Size: 13pt (34 px)
- Move align upper left corner with background
- Save the file
Put the new files under version control
Start VPN
Commit your changes

4 Do Backups

Make sure the engineering manager has a "server image" -- a binary image of everything on the server that can be restored in an instant. It's the ultimate fail safe against things going wrong.
Back up all server files to a new directory in the local system, for the following reasons:
a. You'll be copying the files on your local system to create the new instance. You want to make sure they're the same as the ones that are currently running on the server.

b. Uploaded images, in particular, are stored in a the file hierarchy. (The Wiki database contains page content, but the database only has pointers to the files. The files themselves are stored in the images/ directory and it's many subdirectories.)

c. Images that were uploaded to the wiki generally come from the SVN repo, under techpubs/images. After that, they're in the server's images/ dir, but not in the local files. Copying the image files from the server to your local system makes sure that you have them all, and that they are all in the right place.

d. If anyone made a change to the other files, at any time, you'll have a copy of that as well.
Notes:
Backing up to a new directory preserves your current copy, just in case someone made an unfortunate change on the server.

The fastest way to do the backup is to log in to the server, make a zip, and download that. (Downloading individual files takes forever.)
Process:
A. Login to the server as root (PuTTY)
B. Backup MediaWiki files:
Login to the server as root

cd /usr/share/mediawiki

zip -rvT {wiki}.zip {wiki}/

Download the zip

Extract to {newWiki}
C. Backup Apache config files:
cd /usr/share/mediawiki/apache_config

Execute ./get_conf to copy the mediawiki.conf and phpMyAdmin.conf configuration files from /etc/httpd/conf.d

Execute ./try_setup to create a copy for editing and one for reverting to

Add a date to the mediawiki.conf file, to make it a backup copy

Use ftp/FileZilla to transfer the new files to \www\apache_config

5 Prep Database

Login to the server as root (PuTTY. See email)
View /etc/httpd/conf.d/phpMyAdmin.conf (first page)
Go to http://ipchicken.com to verify your IP address
In the <Directory /usr/share/phpMyAdmin> section, verify that the IP address is allowed.
If it isn't:
- Add the address
- Save the file
- Tell Apache to re-read it: service httpd reload
Note:
We're using a router, so each machine in the building has the same (virtual) IP address.
This step is only be needed when coming from some other location.
Enable PhpMyAdmin
Login to PhpMyAdmin
Clone the Database
a. Visit the most recent database (e.g. wiki80)

b. Click Operations

c. Copy database to: wiki{newVersion}

d. Radio button: Structure and data
e. Checkbox options:
CREATE DATABASE before copying

Switch to copied database
f. At lower right corner of that section, click [Go]
A message appears at the top of the page saying that the database has been copied.
Disable PhpMyAdmin

6 Prep the Sandbox

Note: This process parallels the Wiki upgrade process recommended at http://mediawiki.org, but it goes through the installation process to make sure that the internal "script path" settings are configured correctly.

6.1 Backup Wiki Files to Local System

This part of the process ensures that all images uploaded to the server are backed up locally. (Important because images are typically uploaded from the SVN repository, rather than from the local directory.) It also ensures that any other changes made to the server files (perhaps by others) are in the local copy.

If you already made a zip-backup files in the earlier steps, just save that zip for a backup. That way, you have:

a. Your version of the files, on your local drive.

b. The files from the server, in the zip.

c. A copy of those files in the {newWiki} branch, ready to be modified.

Otherwise:

Login into the server
Go to the mediawiki directory: cd /usr/share/mediawiki
Archive the current version of the wiki: zip lj{current_version} ...
Use ftp/FileZilla to download it to c:/wwww
Use 7zip or WinZip to unzip the archive contents into c:\wwww\lj{current_version}

6.2 On your local system:

Either unzip the zip of the server files into the new directory, Copy the current wiki:
C:/www/{currWiki} => C:/www/{newWiki}
Rename these files and folders so they're not overwritten by the install:
- /extensions --> /extensions1
- /images --> /images1
- /skins --> /skins1
- /LocalSettings.php => LocalSettings_mine.php
Download the latest production version of MediaWiki.
- Visit Special:Version to find out which version is currently running.
- Get latest files from
  - http://mediawiki.org
  - Download > Get MediaWiki (.tar.gz)
  - Pick latest production version that has a green checkmark (indicates it is stable)
- Use 7-Zip to uncompress the files
  - Verify the directory structure (It probably untars to mediawiki-{version}/)
  - Copy the contents to the local instance of the new wiki (ex: C:/www/lj81)
Remove these folders:
- /extensions
- /images
- /skins
Rename these:
- /extensions1 --> /extensions
- /images1 --> /images
- /skins1--> /skins
Rename robots.txt_ALLOW to robots.txt, to turn away search robots.
Copy the freshly minted logo and icon files from the SVN repo at Relationals/techpubs/images/logos to skins/lj7monobook in the new wiki.
Remove LJ_Logo.png and lj.ico
Rename LJ_Logo_{newVersion}.png and lj_{newVersion}.ico to replace them.
Zip up the new folder in File Explorer:
- New > Compressed (Zip) folder
- Open the new zip archive
- Copy the new wiki folder into the open window
  (Attempting to copy into the file doesn't seem to work, at times.)
Use ftp/FileZilla to copy it to the hosting server.

6.3 On the server:

Login as root
Unzip the zip file:
- cd /usr/share/mediawiki
- unzip -a {newWiki}
  where -a converts line endings in text files from CR/LF to LF
Make everything owned by the ftpuser, in the ftpgroup
- chown -R ftpuser:ftpgroup {newWiki}
Make the config/ dir writable for the installation process, and images/ writable to enable uploads:
- cd {newWiki}
- chmod -R a+w config images

6.4 Install MediaWiki

From a browser, navigate to:
http://lj.platformatyourservice.com/{newWiki}

Click set up the wiki.
(The installation process ensures that PHP scripts which comprise MediaWiki are set up with the correct script path. It's a necessary step, because that value is difficult to retrofit.)

1.16.5 installation shows this. (1.17 install fails, because it needs PHP 5.2.3--but it fails without saying that!

PHP 5.1.6 installed
Found database drivers for: MySQL PostgreSQL SQLite
PHP server API is apache2handler; ok, using pretty URLs (index.php/Page_Title)
Have XML / Latin1-UTF-8 conversion support.
Session save path (/var/lib/php/session) appears to be valid.
PHP's memory_limit is 128M bytes.
Couldn't find eAccelerator, APC or XCache; cannot use these for object caching.
Found GNU diff3: /usr/bin/diff3.
Found ImageMagick: /usr/bin/convert; image thumbnailing will be enabled if you enable uploads.
Found GD graphics library built-in.
Installation directory: /usr/share/mediawiki/rn63
Script URI path: /rn63
Installing MediaWiki with php file extensions
Environment checked. You can install MediaWiki.

Fill in configuration info:
- Site config
- Wiki name: PlatformSupport
- Contact email: {your email} --or root@localhost??
- Language: en - English
- Copyright/license: No license metadata
- Admin username/password: WikiSysop / root pw
- Object caching: No caching
  (Unless and until memcached ("Memcache-D: The memory caching daemon) is installed and server addresses can be provided.)
- Email config
- Email features (global): Enabled
- User-to-user email: Disabled
- Email notification about changes: Disabled
- Email address authentication: Enabled
- Database config
- Database type: MySQL
- Database host: localhost
- Database name: wiki{new_version} Ex: wiki81
- DB username: <name used to login to PhpMyAdmin>
- DB password: <password for same>
- Superuser account: None
- Database table prefix: {blank}
- Storage engine: InnoDB
- Database Char Set: MySQL 4.1/5.0 binary (efficient)
Click [Install MediaWiki].
The install finishes and gives you a page that echoes your settings. The /config directory now has a LocalSettings.php file created by the install.
Copy \config\LocalSettings.php to parent dir:
- cp config/LocalSettings.php .
Test access to the wiki at http://test.platformatyourservice.com/{newWiki}
- Undefined variables look like undefined templates
- And the logo is missing
- But the page can be reached.
Nuke the config/ dir:
- rm -rf config/

6.5 Customize the Configuration

6.5.1 Locally:

In FileZilla:
- Download LocalSettings.php
- Go to includes/parser
- Rename the local Parser.php to Parser_mine.php
- Download Parser.php. Rename it Parser_theirs.php
Until the patch I submitted is available, merge modifications from the old includes/parser/parser.php into the new one,
in order to generate a period after first-level numbered headings:
- Start TortoiseMerge:
  Base File = Parser_theirs.php
  
  Their File = Parser_theirs.php
  
  My File = Parser_mine.php
- Merge changes
  Left pane shows diffs between THEIR file and BASE file
  
  Right pane shows diffs between MY file and BASE file
  
  Search for "# count number of headlines for each level
  
  From there to "We're at a level one head. Add a dot after it", should be merged in
  
  Lines 3646-3652 in the 1.17 file.
  
  Save As: Parser.php
Merge saved LocalSettings_mine.php and LocalSettings_theirs.php into LocalSettings.php
- Start TortoiseMerge:
  Base File = LocalSettings_theirs.php
  
  Their File = LocalSettings_theirs.php
  
  My File = LocalSettings_mine.php
- Save as: LocalSettings.php
Change these settings:
- $ljVersion = "Version {new_version}"; Ex: "Version 9.0"
- Verify:
- $wgScriptPath = "/{newWiki}"; Ex: "/lj90"
- $wgDBname = "wiki{new_version}"; Ex: "wiki90"
- Change:
- Use the "secret key" from the newly generated file (internal DB access)
- $articlePath = "$wgScriptPath/$1";
- $wgEnableUploads = true;
- Comment out Google analytics, so they're disabled.
In FileZilla, upload LocalSettings.php and includes/parser/parser.php

6.5.2 On the Server:

Log in as root
Update the MediaWiki database (unless you have installed the exact same version):
cd /usr/share/mediawiki/maintenance

php update.php
- Checks and updates the schema. inserts missing tables, updates existing tables,
and moves data around as needed.

- Usually just works.

- In case of error, see http://www.mediawiki.org/wiki/Upgrade#Run_the_update_script
Update the Apache configuration
cd /usr/share/mediawiki/apache_config

Modify mediawiki.conf_new:
a. Copy the <Directory> section for the current version of the wiki

b. Modify the path to point to the new wiki folder:
<Directory /usr/share/mediawiki/{newWiki}>

c. Add an Alias statement that points to that folder
Alias /usr/share/mediawiki/{newWiki}
Load the new configuration file:
./try
(Does a copy and service httpd reload)

7 Test the Sandbox

Browse to the new wiki and check that the following operations work as expected:

Viewing pages in different skins
Editing pages
Uploading a file

If Favicons don't appear in FireFox, or have old values, do the following:

Install the SQLLite plugin for FireFox
Follow these directions to clear the Favicon cache (the moz_favicon table)
http://www.pcmech.com/article/clearing-all-favicons-from-firefox-3-cache-how-to/

8 Change Platform Pointers

Once the new version is verified"

Send a note to eng (mostly for Q/A) to change the help pointer in their localhost version so it points to the new branch at http://platformatyourservice.com/{newWiki}
In qamain, change the help-content source link to point to the new wiki:
- Login as admin
- Configure Service Settings > Edit > Basic Service Settings > Help Domain
- Change to .../lj_{new_version}_/
  (Don't forget the slash at the end.)

9 Modify Wiki Content

In the old wiki:

Remove the pre-release versions of these pages from the prior version of the wiki, if they exist:

Release Notes / Upgrades and Enhancements
Doc Notes
ISV Release Notes pages

Tip: For your own sanity, log out of the old version of the wiki at this point. That way, when you follow a link to the old version, you won't start editing it by mistake, thinking you're in the new one.

In the new wiki:

Change redirect-pages:
- Release Notes
- ISV Release Notes
- On the Doc Notes page, add link to Version {New} Doc Notes
Change these locations, if they are changed in the server build:
- Template:JAVA_DOCHOST --+-- value used to generate javadocs in server/build/build.xml
- Template:J2EE_DOCHOST --+

10 Clean up and Housekeeping

Log in to the server as root
cd /usr/share/mediawiki/lj_{new_version}_/maintenance
From the command line, in the maintenance directory:
- Remove old, deleted images that are taking up space in the archive:
php deleteArchivedFiles.php --delete
- Remove versioned copies of images that are taking up space in the archive.
php deleteArchivedRevisions.php --delete
- Once a decade, clear out the revision history for the pages:
php deleteOldRevisions.php --delete

Clear the image-history to minimize the wiki footprint: Enable phpMyAdmin Visit http://{wikidomain}/phpMyAdmin Select the new database Go down to the oldimage table Click the "Empty" icon (at the end of the icons) to clear the image history in that table Disable phpMyAdmin

Search

where to start

learn more

Tools

Personal tools