Creating a customized installation guide

StartInstall is a starting point for step-by-step instructions to install a basic Foswiki. Potential Foswiki admins can choose the guide that corresponds to their target environment, and click through a sequence of pages that break down the installation procedure into various steps.

One of the target environments listed on the StartInstall page is a generic Unix on Apache environment. The generic Unix on Apache guide, located at InstallOverview, is based on System.InstallationGuide. In order to simplify the creation of new guides, the generic guide is designed to be reusable, so a customized guide for a different environment can inherit all of the content from the generic guide, and just provide overriding pages for the steps that differ.

Steps to create a customized installation guide

Overview (see detailed steps below):

• Create an InstallOverviewMyVariant topic.
• Clone any topic from the generic Unix with Apache guide, adding MyVariant at the end. Change the topic as desired.
• When complete, edit StartInstall and InstallingOnSpecificPlatforms to link to InstallOverviewMyVariant.

See InstallOverviewSolaris10 for an example of a customized InstallOverview topic, and the various links from this page with a "Solaris10" suffix, such as InstallStepSetPermissionsSolaris10, for examples of customized installation steps.

Create an InstallOverviewMyVariant topic

Create a new topic, InstallOverviewMyVariant. Put the following raw text in the topic:

%INCLUDE{"InstallOverview" IGVariant="MyVariant"}%

You now have a new customized overview that defaults to using all the same steps as the generic Unix with Apache guide. The next step is to customize any or all steps for your variant.

Clone any topic from the generic Unix with Apache guide

Customize any topic from the generic Unix with Apache guide by copying the topic to a new one of the same name plus MyVariant at the end. For example, to customize InstallStepSystemRequirements, create a new topic called InstallStepSystemRequirementsMyVariant. You can use the More actions -> Copy topic command.

Edit your new topic by deleting the "---" and all following text at the bottom of the topic. Modify the setting of the IGVariant macro so that it is set to MyVariant.

<div style="display:none;">
   * Set IGVariant = MyVariant
</div>

The setting of IGVariant and its surrounding <div> should now be the last thing in the topic.

Change anything else in the topic as suitable for your customized guide.

Add link to StartInstall and InstallingOnSpecificPlatforms

When your customized guide is ready, edit StartInstall and InstallingOnSpecificPlatforms so they link to InstallOverviewMyVariant.