Difference between revisions of "User:Aeric/Wiki Admin Guide"

Latest revision as of 19:09, 2 June 2015

1 Overview

1.1 Terminology

wiki: a collection of pages that are both displayed and edited online, and which allows for easy interlinking and transclusion of material, for reuse.

dev wiki: The pre-release (or "development") version of the wiki, containing information on features that are not yet released. Location: /usr/share/mediawiki/aadev

production wiki: The most current and up-to-date version of the wiki that is visible to customers. Documents all platform features currently available in the cloud. Location: /usr/share/mediawiki/aawiki

backup: A dated zip file that contains database content (in a .sql file) and all wiki files for either the production or dev versions of the wiki. E.g. dev_backup_<date>.zip

version or versioned wiki: A point-in-time copy of the production wiki that snapshots the features available in the platform installable, for reference by an on-premise installation of that platform version.

archive: A zip file containing database content and wiki files for a wiki version. E.g. aa90.zip

1.2 How the Wiki Works

Major concepts:

Mediawiki consists of a MySQL database, plus a collection of PHP scripts and supporting files in the Wiki directory.
The textual Wiki content is contained in a database.
Image files are stored in a hashed system of nested directory folders under {wiki}/images. (The database contains links to them.)
Together, the database plus the files and scripts contained in the wiki's directory folder make up the Wiki that the user sees.

The main configuration script:

LocalSettings.php

$wgDBname - The variable that names the database in the MySQL space,

accompanied by the login information and the mysql "secret key" for the space

$wgScriptPath - This variable is used to generate Wiki links. E.g. "/wiki".

The wiki will start if it's wrong, but all of the links it generates will point to this location. Much internal processing will look there for scripts, as well.

Standard directories:

extensions/: MediaWiki plug-ins that have been downloaded and "installed" by referencing them in LocalSettings.php. (Since pages are loaded dynamically, once the extension is present, it is automatically part of the Wiki. No restart needed.)

images/: A directory hierarchy that contains the image files after they have been uploaded. The Wiki stores them there when you upload an image, and keeps a pointer to them in the database.

skins/: The images and CSS files that create the "wrapper context" (headers, nav pane, etc.) for the wiki content. (The lj7monobook skin was customized to make the nav pane wider.)

Added directories:

_v16_skins/: A copy of the skins that came with MW 1.16.5, before the nav pane was widened. Saved so that a diff tool can be used to identify those changes and any others.

custom_images/: Header images and favicons used by the browser for bookmarks and tabs.

download/: A directory we added to hold files we want to reference in the wiki. (Only image files can be uploaded to the Wiki. But that's ok. Image loads are done painfully, one at a time. Files in the download/ folder can be easily updated en mass. (Image files need to be uploaded so that "links" to them coded in the wiki cause the image to be displayed.)

1.3 How Links to the Wiki Work

The mapping of URLs to Wiki's is set up in the mediawiki.conf file.

Current Version Links

These URLS point to the latest released (cloud) version of the Support Wiki:

http://{subdomain}.agileappscloud.info/wiki - AgileApps Live support wiki

http://{subdomain}.platformatyourservice.com/wiki - LongJump wiki

Those are the best links to send to current customers, as they’ll always point to the latest pages. And they will always stay at the top of the Google search rankings, by virtue of being the most heavily accessed Wiki pages.

Versioned links

Customers with an on-premise installation need to refer to a version of the wiki that matches their installation:

http://{subdomain}.agileappscloud.info/aa90

http://{subdomain}.platformatyourservice.com/lj82

Use scripts/versionProductionWiki to create an versioned copy of the production wiki when an installable version is released.

Pre-Release Links

To review a pre-release version of AAL content, use this link:

http://{subdomain}.agileappscloud.info/aadev

That link points to the "development" (pre-release) version of the wiki.

(Since updates happen every three or four weeks, customers will rarely need it.)

2 Configuring the Wiki

2.1 Configuration Notes

The wiki is hosted at Rackspace.
The server can be accessed with a VPN connection, using either FTP or SSH.

FTP gives access to all of the Wiki files, which is generally sufficient.

(Access details are in emails.)

DNS entries that point to the server are agileappscloud.info and platformatyourservice.com.
Location of any given wiki is /usr/share/mediawiki/{wikiName}
Multiple subdomains are set up using Apache, the DNS server, and LocalSettings.php.
The DNS entries determine which subdomains are known to the world.
The wiki name in the url determines which wiki is accessed. (E.g. /wiki)
The LocalSettings.php file in that wiki uses the subdomain to determine which skin is used.
The skin determines which logo is shown, which platform name to use, and the settings for several other variables, including the site name.

Organization of the mediawiki.conf Configuration File

There are two <VirtualHost> sections, one for each virtual server:
(agileappscloud.info and platformatservice.com).

Inside each virtual host, there is a <Directory> section for each wiki that can be accessed, as well as an Alias setting that maps the {domain}/xyz URL to the /usr/share/mediawiki/xyz wiki folder.

In the AgileAppsLive domain, the "/wiki" alias points to the aawiki wiki, as does the "/aawiki" alias.

When scripts/versionProductionWiki is run to make a versioned copy of the production wiki, a new directory-section and alias are created for it. E.g. "aa90".

Each <Directory> contains a number of URL rewrites that are needed to make the wiki work properly. Unfortunately, they need to be copied for each directory.

Attempts to do global rewrites failed, as recorded in notes at the top of the file. However, the rewrites were not attempted inside the <VirtualHost> headings, as those came later.
So it is possible that a clever configuration could cut down the size of the <Directory> segments.
But, as the notes in the file attest, the Apache rewrites frequently do not work as documented--so the actual semantics must be discovered by trial and error. (A rainy day project for sure, not worth the time given that we have a working system.)

2.2 Configuring Apache

The Apache configuration file is /etc/httpd/conf.d/mediawiki.conf.

Always preserve the original and edit a copy in /usr/share/mediawiki/apache_config

To edit, either:

SSH to the server using PuTTY or the SSH shell, and use a line-oriented editor like nano.
Use FTP to bring the file back to your workstation, and use a terrific editor like NotePad++

2.3 Maintenance Scripts

To use these scripts:

Using PuTTY, log in to Rackspace
cd /usr/share/mediawiki/apache_config

Scripts:

./get_conf

Gets a copy of the three main configuration files, primarily for backup:

httpd.conf

phpMyAdmin.conf

mediawiki.conf

./try_setup

Copies the current config file as mediawiki.conf_sav.

If no else is editing mediawiki.conf, then mediawiki.conf_new has the same content, and is ready to be edited. Otherwise, copy _sav to _new before you begin.

./try

Put mediawiki.conf_new in place and restart the server.

For a quick test, refresh the page for each of the main wikis:

If you can see the page and the generated links are correct, the wiki is usable.

If you've done any work on the skins, then test the changes, as well

./revert

Put mediawiki.conf_sav back in place, in case the _new version didn't work.

Apache References

2.4 Apache Notes

2.4.1 Commands

RedHat commands worth knowing:

service httpd restart - Restart Apache (generally unnecessary. Sometimes useful, "just to be sure")
service httpd reload - Reload the configuration files

2.4.2 mediawiki.conf

The configuration file for MediaWiki is /etc/httpd/conf.d. mediawiki.conf, where:

etc (eht-cee) is the "et cetera" container for stuff added to the system
httpd is the HTTP Daemon (Apache)
conf.d is the directory of configuration files (all files in this directory are read by Apache when it starts or reloads.)

Important:
All files in that directory are processed, so make backup files elsewhere.

2.4.3 About that query string

Motivation: Pages with plain names seem to work properly. The incoming link is converted to the short URL form, and TOC entries have that form, as well.

But bookmarks that go to old pages that have :, /, or ! in them don't get a URL rewrite, because those characters don't seem to be handled by the URL-segment-at-a-time matching rules. (They must be MediaWiki matching rules, because Apache is *not* doing the redirect. MediaWiki is.)

Idea: We could make a redirect.php page that parses the query string, creates the new URL, and sends a 301-redirect back to the browser. That would be cool. But it's a fair amount of work for a few special pages that, over time, will no longer be bookmarked.

2.5 Testing a Wiki

To test a new wiki:

Go to the wiki without specifying a destination page
- Ensure that the home page is displayed
Click a link
- Ensure that the page displays
- Ensure that the link is correct

If you were testing an Apache configuration change:

If all is not well, use ./revert to restore the old Apache configuration settings. (You shouldn't need to undo changes to LocalSettings.php, but be prepared to do so, just in case.)

If all is well, make backup of mediawiki.conf_new:

cp mediawiki.conf_new mediawiki.conf_{year}_{month}

3 Copyright Notices

4 Notes

General:

LJ Copyright range is 2003-current
AA copyright range is 2013-current
In the LJ wikis, the plan is to show "Copyright and Legal Notices" in the footer for LJ, AT&T and ISV skins.
That text will link to the Copyrights page. (Awaiting approval.)

Javadocs:

Cannot regenerate LJ javadocs, due to new and removed APIs.
Need to do a global search & replace to fix them.
In consequence, any time an LJ wiki is created in a new year, the global search & replace needs to be performed.
In the LJ Javadoc footers:

The link could point to the copyrights page in the current wiki version (AA or LJ), but it would take a 8.1 user, say, to the 10.0 wiki. Searching from there would lead to the wrong material.
The link could point to the copyright in the corresponding version of the wiki, but it's harder to keep up to date, and is one more thing to get correct each time a LJ wiki is released in a new year. (Something that is highly likely to happen to give new features to ISVs.)
THE ONLY VIABLE OPTION: The copyright link points directly to http://documentation/softwareag.com/legal

5 Affected Pages and Files

97 operations, in total.

5.1 Modify Settings

Edit files in FileZilla & post to server, using the #Settings for AA and LJ.

Page / Wiki	aadev	aa100	aawiki	ljwiki	lj100	lj90	lj82	lj81	rn63
LocalSettings.php (footer link)	X	X	X	X	X	X	X	X	X
skins/lj7monobook.php (footer entries)	X	X	X	X	X	X	X	X	n/a
skins/isvMonoBook.php	n/a	n/a	n/a	X	X	X	X	X	n/a
skins/att.php	n/a	n/a	n/a	X	X	X	X	X	n/a
skins/rnmonobook.php	n/a	n/a	n/a	n/a	n/a	n/a	n/a	n/a	X

Fix needed to activate 81 lj skin:

BOGUS ERROR:

The problem was that My Preferences > Skin was set to use the custom skin.

(Sadly, there does not seem to be a setting that says, "None of the above. Use the default.")

Additional fixes to activate footers in ATT & ISV skins

Problem:

Footer-list code was included in an HTML comment-block

Solution: Moved HTML end-comment from after footer list (</ul>) to before start (<ul>)

Problem:

Files saved in BeyondCompare were in some format that had CR with no LF.

When read as a PHP script, the line that set the footer was attached to the comment line above.

Solution: Open in NotePad++ and fix Line Endings (Edit > EOL Conversion > Unix format)

5.2 Modify Wiki Pages

Page / Wiki	aadev	aa100	aawiki	ljwiki	lj100	lj90	lj82	lj81	rn63
MediaWiki:Copyright (adds non-link text)	X	X	X	X	X	X	X	X	X
Copyrights (legal text)	X	X	X	X	X	X	X	X	X

5.3 Fix AA Javadocs

Modify build file to set Javadoc date and insert it into Javadocs footer

 <format property="YEAR" pattern="yyyy" />

</tstamp>

...

Regenerate

Wiki:	aadev	aawiki	aa100
Post	X	X	X

5.4 Add copyright notices to AA PDFs (/articles)

Add copyright notice and details to:
- 2013- Build an App
- 2013- Customizing ServiceDesk
- 2014- Intro to DCM
Post to aadev.
Publish aadev to aawiki.
In aa100:
x-Publish the separate articles from SVN.

x-Copy the article index page from aadev.

x-Change the link on the Welcome page to point to the index-page.

Page / Wiki	aadev	aa100
Customizing Service Desk	X	X
Build an App	X	X
Intro to DCM	X	X

5.5 Fix LJ Javadocs

2003-current

Cannot regenerate these, due to Access Profile and other APIs that do not apply to LJ.
Regular expression find: Copyright .*
Replace with:
<a href="http://lj.platformatyourservice.com/wiki/Copyrights" target="_blank">Copyright and Legal Notices</a>

Process needs to be repeated for a new wiki in a new year

Wiki:	ljwiki	lj100	lj90	lj82	lj81	rn63
Zip and download	X	X	X	X	X	n/a
Global search & replace	X	X	X	X	X	n/a
Rezip, upload, unpack	X					n/a

5.6 Add copyright notices to LJ PDFs (/whitepapers)

Add copyright notice and details:

2011- ljAgile Dev and Test
2011- ljCollaborative Development
2011- ljHosting Infrastructure
2011- ljOperational Policies
2011- ljSecurity Features

Regenerate and upload to wikis:

Page / Wiki	add notice	gen PDF	ljwiki	lj100	lj90	lj82	lj81
ljAgile Dev and Test	X	X	X	X	X	X	X
ljCollaborative Development	X	X
ljHosting Infrastructure	X	X
ljOperational Policies	X	X
ljSecurity Features	X	X

6 Settings

6.1 AA WIKIs

LocalSettings.php

Add:

$YEAR = date('Y');

line 139:

$wgRightsPage = "Copyrights"; # Title of a wiki page that describes licenses and copyrights
$wgRightsUrl = "";            # -OR- Title of an external URL that does the same
$wgRightsText = "Copyright &copy; 2003-$YEAR Software AG"; 
                              # Text of the link created for the above
$wgRightsIcon = "";           # Image to place at left side of footer

MediaWiki:Copyright

$1.

6.2 LJ WIKIs

LocalSettings.php (line 139)

$wgRightsPage = "Copyrights"; # Title of a wiki page that describes licenses and copyrights
$wgRightsUrl = "";            # -OR- Title of an external URL that does the same
$wgRightsText = "Copyright and Legal Notices"; # Text of the link created for the above
$wgRightsIcon = "";           # Image to place at left side of footer

MediaWiki:Copyright

$1.

Javadocs footer:

<a href="http://lj.platformatyourservice.com/wiki/Copyrights">Copyright and Legal Notices</a>

6.3 Skins

skins/lj7MonoBook.php, line 345
skins/ATT.php, line 655
skins/IsvMonoBook.php, line 547

//Generate additional footer links
// removed  'numberofwatchingusers', 'credits', 'privacy', 'about', 'tagline'
$footerlinks = array('copyright', 'lastmod', 'viewcount');

Notes:

Conditional tests for skin-names don't work inside MediaWiki:Copyright
Template transclusions DO work, but conditional tests inside those templates do NOT work
Solution: The logo is at the top of the page, so use "Copyright and Legal Notices" for LJ, ATT, and ISV skins

6.4 Copyrights Page

Copyrights - text supplied by legal

Copyright © 2003-{{CURRENTYEAR}} Software AG, Darmstadt, Germany and/or Software 
AG USA Inc., Reston, VA, USA, and/or its subsidiaries and/or its 
affiliates and/or their licensors.

The name Software AG and all Software AG product names are 
either trademarks or registered trademarks of Software AG and/or 
Software AG USA Inc. and/or its subsidiaries and/or its affiliates 
and/or their licensors. Other company and product names mentioned 
herein may be trademarks of their respective owners. 

Detailed information on trademarks and patents owned by 
Software AG and/or its subsidiaries is located at
http://documentation.softwareag.com/legal/.

This software may include portions of third-party products. For 
third-party copyright notices and license terms, please refer to 
"License Texts, Copyright Notices and Disclaimers of Third Party 
Products". This document is part of the product documentation, 
located at http://documentation.softwareag.com/legal/ and/or in 
the root installation directory of the licensed product(s).

7 Customizing the Wiki Look and Feel

7.1 About Customizing

These features are used to customize the wiki for generic ISV use, or for a branded wiki.

7.1.1 Platform-specific Versions

To create a branded version of the Wiki for a particular ISV:

First, set up a subdomain for the ISV.
Every customization is controlled by the use of that

subdomain when accessing the common Wiki. For example, lj.platformatyourservice.com and isv.platformatyourservice.com both go to the very same place--but the different subdomains changes the wiki's look and content.

Then customize the look and feel for that brand.
Finally, take care of the Wiki content.

Note: All changes should be made locally, and then uploaded to the server. Note, too, that it would be highly desirable to test the changes before uploading them. To do that, it is necessary to set up a server that runs the local copy of the files. (One day, this too shall be done...)

7.1.2 Product-Specific Versions

To create a branded version of the Wiki for a particular application:

Create a new domain for that product.
Customize the look and feel for that product
For example, sidebars that have product-centered links only, rather than links to generic design and development pages.
(We may or may not do this...)
To link to generic platform design & development pages, use external links ([url name]) rather than internal links ([[page name]]). (The Google page search should then be confined to the product pages, since they're no longer in the same domain.)

How it works:

We're using rally360.info for the latest incarnation of the corporate wiki.
The default skin for rally360.info is the same as that used by hd.rally360.info

In other words, the "hd" skin is the default
where "hd" stands for "HelpDesk"

Future products in the same theme ("360-degree circle with customer at the center") will have their own subdomains. For example, "crm" for Customer Relations Management.

To change the product name:

The product pages are in the "HelpDesk:" namespace.
That name is defined by a variable--{{HD}}--so it can be changed.
Links to those pages and transclusion references use that variable, so they can be easily changed by modifying LocalSettings.php
Two things then need to be done:

a. Rename all pages to reflect the new namespace.

b. Change all REDIRECT pages, because the variable cannot be used in them.

(Change all occurrences of "HelpDesk:" to "NewName:")

7.2 Prerequisites

You'll need to have these things handy to set up the customized version:

Content Controls
- What brand name replaces the "AgileApps Cloud platform"? (EnterpriseBrand--always follows the word "the", typically followed by "platform".)
- What label replaces "LongJump" in the Eclipse Plugin? (BrandLabel)
  (and in email-sync, when enabled.)
- What brand name to use for the Service and Support application? (HelpDesk)
  - Always follows the word "the"
  - HelpDesk is the original default.
  - It requires extra work to make a branded version of the HelpDesk page, so don't change it, if possible
    (A new page needs to be created for the branded version, and {{:Common:HelpDesk}} content needs to be transcluded into it.)
- Are the branded whitepapers available?
- Should development information be displayed (Eclipse plugin, APIs, classes, etc)
- Should ISV info be displayed?
- Should MSP info be displayed?
- Should a training link be displayed? (TrainingLink) If so, where should it point?
Font Style (Wiki default is "Sans Serif")
Color of horizontal & vertical bars on Welcome page (default is lime green)
Logo image
- Displays in upper left of every page.
- 160 pixels wide x 135 high. Any format browsers can handle.
Icon image
- Displays in the browser's address bar, in bookmarks, and in browser tabs
- 32 x 32 pixels, .ico format (icon format)
- Create using the free[ http://icofx.ro/ IcoFX] utility
TBD
- Support Link
- Content of Subscription Summary page
- Recipient of Wiki Feedback, if any (currently, this feature is disabled)

7.3 Set Up a Subdomain

The subdomain is the master switch that turns on everything else.

In UltraDNS, add a DNS entry for the subdomain
(Directs the subdomain-URL to the HOST IP address).
- Access CPanel Securely > Subdomains
- Create subdomain: {name} (lowercase)
- Document root: public_html
At the bottom of mediawiki.conf, add a subdomain entry to the <VirtualHost> tag:
- ServerAlias {name}.platformatyourservice.com
- Process:
a. In www/apache_config, edit mediawiki.conf_new

b. Upload the file

c. In PuTTY, cd /usr/share/mediawiki/apache_config

d. Use ./try to test it. Use ./revert to go back to the previous version.

e. When changes are tested, cp mediawiki.conf_new mediawiki.conf_sav.
(The new version is now the version you'll revert to, the next time you test changes.)

r. Also copy it to mediawiki.conf_{date} so you have it for future reference
Finally, consider the impact of the subdomain on the #Customized Wiki Search

7.4 Create a New Skin

In {wiki}/skins, copy a folder for the new look and feel
(This is where CSS styling and images will be placed.)

E.g. Copy skins/custom/ to skins/isvname/ (lowercase)
In the skins folder, copy the two skin-index files:
- Copy Custom.php to IsvName.php (camelcase)
- Copy Custom.deps.php to IsvName.deps.php (camelcase)
- File IsvName.deps.php doesn't need to be touched.
- In IsvName.php, do two case-sensitive substitutions:
  - Custom ==> IsvName (camelcase)
  - custom ==> isvname (lowercase)

Learn more:

This is an old page with excellent directions:
http://www.mediawiki.org/wiki/Manual:Skins/From_Meta#Creating_a_Skin_based_on_MonoBook_.281.6.x.29
This is the index pointing to newer pages. They're more detailed, but often lack good, task-oriented instruction:
http://www.mediawiki.org/wiki/Manual:Skins

7.5 Configure the Wiki for the New Subdomain and Skin

In /www/{wiki}/LocalSettings.php, copy the "custom" else-if clause.
Change the sitename variable, $wgsitename.
Note: This title is still used to condionalize Wiki content, in some places.
Point to the new skin in $wgDefaultSkin.
Make sure the image and icon pointers are going to the right files.
Customize the wiki variables.

Note: Currently, these variables are defined as "templates" in the Wiki:

Template:DOCHOST: The location of configuration files, code samples, platform javadocs, and other resource files referenced in the wiki.
Template:JAVA_DOCHOST: The location of the standard Sun/Oracle javadocs. (This value should match the one used when generating platform javadocs.)

The expectation is that these values are wiki-specific, rather than than skin-specific. (They use Wiki variables so they automatically point to the current wiki's download files.) They are noted here, only in case it becomes desirable to point to skin-specific locations at some future date.

7.6 Change the Graphics

In custom_logos, copy and edit the graphics files:

Icon image: aa###.ico, where "###" is the version number
- Appears to the left in browser address bar, browser tabs, and bookmarks.
- 32x32 pixels
- The free IcoFX utility is good for editing.
Logo image: aa###.png, where "###" is the version number
- GIF, JPG, or PNG
- 160w x 135h pixels recommended, but height <= 135 is fine.
- (MediaWiki recommends 135x135, but we sidebar width has been increased to 160px in our instance.)

7.7 Modify the Styling

7.7.1 Working with Skins

A few things to know going in:

All of the skins are based on the default MONOBOOK skin
When you set the default skin in LocalSettings.php, you're setting the default for new users.
Anyone who isn't logged in will see your changes when they refresh the page.
But you, being someone who has logged in so you can edit stuff, will always see the skin you had before!
To fix that, go to My Preferences > Skin and select the skin you want to use.
Or, to check out an individual page, add &useskin={skin} to the URL.
For example: ?useskin=lj7monobook or ?...&useskin=lj7monobook

Learn more:

This page explains the names of the divs in the skin, and how they're used:

http://meta.wikimedia.org/wiki/Customization:Explaining_skins#Major_style_blocks_by_name

Best instruction I've found to date:

http://charlesmartinreid.com/wiki/Skinning_MediaWiki

Tip:
When viewing page source, all of the variables are defined at the top of the page, starting around line 35. For example:

  <script type= "text/javascript">/*<![CDATA[*/
    var skin = "isvmonobook";
    var stylepath = "/wiki/skins";
    var wgArticlePath = "/wiki/$1";
    var wgScriptPath = "/wiki";
    var wgScript = "/wiki/index.php";
      ...
    var wgServer = "http://isv.platformatyourservice.com";
      ...
    var wgVersion = "1.15.5";

7.7.2 Making a Custom Sidebar

Sidebars can't have embedded conditionals so if multiple sidebars are needed, copy Template:Sidebar to make one for each skin.

The format is:

Box title
- Bullet item target page | text to display

</syntaxhighlight>

Then create nested conditionals in Template:Sidebar to select the sidebar to display for the current skin.
(Conditionals can be used to choose which sidebar to expand. They can't be used within the sidebar list.)

Learn more: http://www.mediawiki.org/wiki/Manual:Interface/Sidebar#Customize_the_sidebar

7.7.3 Modifying Logo/Layout CSS

The logo layout is controlled in skins/{skin}/main.css.

The main skin is lj7monobook
Adjustments can also be made using the content CSS pages below.

The vertical space available for the logo is controlled in #column-one.

padding-top controls how far down the page the first sidebar entry starts

The height of the box the logo is in is controlled in #p-logo (and #p-logo a below)

height determines the height of the box (>= logo height, <= column-one padding)
margin-top moves the logo image up or down in the available space

The height of #p-logo a needs to match the height in #p-logo, for some reason

height use the same value as specified for #p-logo. It's the link specification. If it isn't set to at least the height of the image, the image doesn't display. So maybe the #p-logo height could be specified as "auto"? (Something to try, in future.)

7.7.4 Modifying Sidebar Width

To change the width of the column, several other things must be adjusted to match.
(If width grows, they must shrink, and vice versa.)

To make a change, see the settings and instructions in MediaWiki:Common.css.

7.7.5 Modifying Content CSS

Where to make changes:

CSS styling that is intended for all looks should be created in Mediawiki:Common.css. That page overrides CSS in all skins.
Skin-specific CSS goes into Mediawiki:{Skinname}.css, where the SkinName is always specified using an initial capital letter followed by lower case.

What to change:

Copy content from one of the other MediaWiki:{Skin} pages for a starter set of things to change.
In particular, set the styles for these elements:
- <hr>
- <body>
- <q> (A "quote" element of some kind? Has some text settings.)
- .horizontal_bar - set the color of the thick horizontal bar.
- .vertical_bar - set the color for a table cell border used to create a thick "vertical bar"
Copy other CSS elements that need to be modified from skins/isvname/main.css

7.8 Customize Locations for External Files

The Wiki points to a variety of external documents. For example: configuration files and code samples. The ability to easily change such locations is highly desirable, both to allow for a local copy of the Wiki and to simplify platform upgrades.

These customizable locations are used in links:

Template:DOCHOST
Template:JAVA_DOCHOST -- points to the location used when building javadocs
Template:J2EE_DOCHOST -- ditto

The key variable is Template:DOCHOST. It contains a URL that points to the download/ area for the current wiki, so that links to files that accompany the wiki don't need to change when the Wiki is moved or renamed.

Usage: Links to external files are coded in the Wiki like this: [{{DOCHOST}}/somefile The link]; The result is a link like this: The link.

Note that the DOCHOST link could conceivably be customized for each skin. That can be done by defining a DOCLINK variable in LocalSettings.php, and then using in the DOCHOST template, like this:

Template:DOCLINK </syntaxhighlight>

With that code, DOCLINK is used if it is defined. If not, the download/ directory that accompanies the current wiki is used.

7.9 Customized Wiki Search

We use the Google Custom Search Engine (CSE) to provide a search that is limited to pages that can be reached by robots, and to limit the results to the text that appears on the page (as opposed to the internal search, which searches the Wiki database--leading to the exposure of pages and text segments that are not limited to a specific audience.

Other advantages of that search:

It tends to list the most frequently accessed pages first
If you specify A and B, it puts pages with A alone or B alone at the bottom of the list, instead of somewhere near the top.
If you specify "A B", it searches for A-whitespace-B, not quote-A-space-B-quote.

At the moment, we have only one search enabled, for rally360.info. At some point, there could be multiple subdomains for different products, but for the moment we have only one (the hd, or "HelpDesk" subdomain).

To modify that engine:

http://google.com/cse
Log in using our Google LongJump account username and password
Ensure that Uday has made you a co-admin for the search(es) (MediaWiki search, currently)
Click the control panel link.
In the sidebar, choose segment in which to make changes.

Notes:

The appearance in the sidebar of the google search and the internal search are controlled in skins/lj7monobook.php, in the range of lines from 283 to 323. The are currently set to:

Display the Google search only in the current version of the wiki (because search robots are allowed only in the current pages).
Display it only in rally360 domain (because that is the domain the CSE covers)
Display the internal search in all other circumstances (calling it "search")
If the CSE is displayed, and the current user is logged in, add an "internal search" box at the bottom, for times when we (the logged in writers) want to search a previous or future version of wiki, or we want to look for text in the database.

We use the Google analytics variable to determine if we are in the current wiki ($wgGoogleAnalyticsAccount, because that is the only time that analytics are enabled.

The results of the Google search are displayed in Site:Search. (The rawHTML flag is set in LocalSettings, to allow the appropriate tag to be inserted into the page.)

7.10 Customize Wiki Content

These variables are defined for each skin in LocalSettings.php.
They are case-insensitive.

7.10.1 Global Variables

Application names (because marketing can change them):

Variable	Definition	Value in Current Domain	Usage
HD	name of the "HelpDesk" application	ServiceDesk	`{{HD}}`

7.10.2 Version Variables

Variable	Value
`{{MySqlVersion}}`	5.5
`{{VelocityVersion}}`	1.7

7.10.3 Skin-Specific Variables

Variable Name	Definition	Value in Current Domain	Usage
Skin	Abbreviated name	HD	`{{#if {{Skin}}\|name\|...\|...else...}}`
Domain	Used in the platformURL template	{yourDomain}	Create platform links using `{{platformURL}}`, instead of `https://...`
platformURL	Template:platformURL Link used to access the platform	https://{yourDomain}/networking	`{{platformURL}}`
BrandLabel	Label used in plugin GUIs (Eclipse, Outlook,...)	LongJump	`{{BrandLabel}}`
EnterpriseBrand	Name of the platform	AgileApps Cloud platform	`{{EnterpriseBrand}}`
BrandName	Template:BrandName Advertised brand	AgileApps Cloud	`{{BrandName}}`
TrainingLink	A link for training sessions.		`{{#if {{TrainingLink}} \| [{{TrainingLink}} Platform Training]}}`
WhitepapersLink	Future. Defined the same way as "TrainingLink", so it is easy to change.

Booleans
ShowWhitepapers	Show whitepapers?	(empty=false) (Fixed branding)	`{{#if {{ShowWhitepapers}} \| ...}}`
ShowOutlookSync	Show info related to Outlook Sync & Email Edition Plugin?	(empty=false)	`{{#if {{ShowOutlookSync}} \| ...}}`
ShowIsvInfo	Show info only ISVs care about	(empty=false)	`{{#if {{ShowIsvInfo}} \| ...}}`
ShowMspInfo	Show info only MSPs care about	(empty=false)	`{{#if {{ShowMspInfo}} \| ...}}`
PlatformAdminInfo	Show tenant configuration	true (empty=false)	`{{#if {{PlatformAdminInfo}} \| ...}}`
ShowInstallInfo	Show info for installers	true (empty=false)	`{{#if {{ShowInstallInfo}} \| ...}}`

7.10.4 Variable Combinations

Use this pattern to conditionalize information intended for all Service Providers (both ISVs and MSPs):

{{#if: {{ShowIsvInfo}} {{ShowMspInfo}} |
__Info for all Service Providers (LJ and ISV domains)__
}}

Note: Information intended for both is generally conditioned using ShowIsvInfo--whether or not that was a wise choice remains TBD. So the combination above isn't strictly necessary.

Use this pattern if it is necessary to distinguish information intended for ISVs (which may mention MSPs) from information intended for MSPs, in Wiki versions that do not include ISV info (e.g. Relationals):

{{#if: {{ShowIsvInfo}} |
__ISV info (ISV DOMAIN) __

| <!-- HideIsvInfo -->
{{#if: {{ShowMspInfo}} |
__MSP info (LJ DOMAIN)__
}}}}

8 Upgrading the Wiki

Note: This process is for upgrading a wiki in place. The process hasn't been fully tested, as it turns out that to Create a New Branch it is necessary to install the wiki, so the paths are configured right internally. We tend to upgrade only when creating a new branch, so this process generally isn't needed. It has been retained in case it turns out to be useful at some future date.)

8.1 Do the Update

This upgrade process is based on the one recommended at the MediaWiki site.

First, find out if an upgrade is needed. Check Special:Version to see what we have.
Create a new directory to put the update into.
If needed: Create a new database.
(If you are doing the upgrade as part of creating a new branch, you have already created a new database, so you can skip this step.)
Unzip the latest production version of MediaWiki.
Get the latest stable production version (the latest version listed in green, or listed with a green checkmark, at
http://en.wikipedia.org/wiki/MediaWiki_version_history.
From the old directory:
- Copy the LocalSettings.php file
- Copy the extensions/ folder
- Copy the skins/ folder
In the release notes for the new version, see if any changes need to be made to LocalSettings.php.
Note: It's possible that the upgrade script below does this. Maybe that's why it wasn't part of the procedure mentioned on the MediaWiki upgrade page. (Dunno)
Enable read-only mode in LocalSettings.php of the old directory:
- $wgReadOnly = 'Upgrading to MediaWiki {version}';
Run the upgrade script in the new directory.
Copy the images/ folder to the new directory.
Swap the old directory and the new directory.

Learn more:

8.2 Test the update

Once the upgrade has been completed:

Browse to the wiki and check that the following operations work as expected:
- Viewing pages
- Editing pages
- Uploading a file
In Special:Version, check that the version shown is correct and that the extensions are present.

@@ Line 1: / Line 1: @@
-How stuff works. See also [[User:Aeric/tests]].
 __NUMBEREDHEADINGS__
-==Background Information==
+==Overview==
-{{:User:Aeric/Background Information}}
+{{:User:Aeric/Overview}}
-==Customizing the Wiki Look and Feel==
+==Configuring the Wiki==
-{{:User:Aeric/customizing}}
+{{:User:Aeric/Configuration}}
+===Apache Notes===
+{{:User:Aeric/Apache Notes}}
+===Testing a Wiki===
+{{:User:Aeric/Test}}
-== Backup Processes -- Deprecated ==
+==Copyright Notices==
-{{Deprecated|Matt set up an autmated process for this.}}
+{{:User:Aeric/Copyright Notices}}
-===Backup the mySQL Database===
-This is the first part of the weekly backup.
-:* backupsql.php -- creates DB backup files in <tt>{curr_wiki}/dbbackup</tt>
-:::<tt><nowiki>http://lj.platformatyourservice.com/{curr_wiki}/backupsql.php</nowiki></tt>
-:* There is a nightly cron job in place on the standby server.<br/>{{TBD|Remove the cron job. Use the cPanel options in Siteground to setup a backup cron job there.}}
-===Backup the entire Wiki===
+==Customizing the Wiki Look and Feel==
-This is the second part of the weekly backup.
+{{:User:Aeric/Customizing}}
-{{TBD|}}
-{{TBD|ToDo: Copy all images into image-files/ directory.}}
-===Historical Backup Retention Policy ===
-#Open FileZilla
-#Open the ftp site (see emailed instructions)
-#Clean out extra backup files in <tt>/dbbackup/lj{curr_version}</tt>
-#* Leave as many as seven (they take a lot of space)
-#* Ideal Ages: 1 wk, 2 wks, 1 mo., 2 mo.s, 6 mo.., 1 yr, 2 yrs
-#Create a local folder for backup. Ex: <tt>/042810</tt>
-#Download all files from <tt>/www/{curr_wiki}</tt> Ex: <tt>/www/lj71</tt>
-===Restoring a Backup (optionally in a New Location)===
-Set up the wiki database:
-# Create a MySQL database for the Wiki content, if one does not already exist.
-# Unzip the backup file:  <tt>gunzip xyz.sql.gz</tt>
-# Import the wiki content into the database: <tt>mysql xyz.sql</tt>
-Set up MediaWiki:
-# Unzip the HTML backup in the new directory location:
-#: <tt>cd {wiki_root_dir}</tt>
-#: <tt>gunzip xyz.gz</tt>
-#: <tt>mv xyz {new_wiki_name}</tt>  # Rename it, if desired
-# Modify <tt>LocalSettings.php</tt>:
-#* Complete the rename by telling the Wiki where it is:
-#*:  <tt>$wgScriptPath = "/path_from_server_root_to_wiki_dir";</tt>
-#::Ex: If the server root dir is <tt>/public_html</tt>, and the wiki is in <tt>/public_html/new</tt>, then the path to script dir is <tt>/new</tt>.
-#* Tell the Wiki where the database is:
-#*:  <tt>$wgDBserver = "localhost";</tt>
-#*:  <tt>$wgDBname   = "{new_DB_name}";</tt>
-#:::On Siteground, the DB name is always {username}_{nameYouSpecified}. That name strategy prevents name-collisions in their shared environment.
-#* Specify the username & password for the database:
-#*:  <tt>$wgDBuser     = "{user}";</tt>
-#*:  <tt>$wgDBpassword = "{password}";</tt>
-==Rename the Wiki==
-{{:User:Aeric/Rename the Wiki}}
-==Release a New Version of the Wiki==
-{{:User:Aeric/Release a New Version}}
-== Create a New Branch ==
-{{:User:Aeric/Create a New Branch}}
 == Upgrading the Wiki ==
 {{:User:Aeric/Upgrading the Wiki}}
-==Appendix: Apache Notes==
-{{:User:Aeric/Apache Notes}}