AO 10463

Annex 20 Template for Installation Manual

Install Document Template

AO 10463
Annex 20 Template for Installation Manual

Table of Contents
1
Introduction............................................................................................................3
1.1
Purpose...............................................................................................................3
1.2
Scope..................................................................................................................3
1.3
General Principles..............................................................................................3
1.4
Quality Control...................................................................................................4
2
Installation Manual.................................................................................................4
2.1
Pre-requisites......................................................................................................5
2.2
Pre-installation Tasks.........................................................................................6
2.3
Installation Procedure.........................................................................................6
2.4
Tasks Description...............................................................................................7
2.5
Post-installation..................................................................................................8
2.6
Technical Tests...................................................................................................8
2.7
Uninstall or Roll-back........................................................................................9
3
Additional Information.........................................................................................10
3.1
Acronyms, Abbreviations.................................................................................10
3.2
Reference Documents......................................................................................10
3.3
Contact Information.........................................................................................10

AO 10463

2/10

AO 10463
Annex 20 Template for Installation Manual

1 Introduction
1.1

Purpose

This document is provided to serve as a template for contractors when they create
installation instructions for a software delivery that is to be installed on the
Publications Office technical infrastructure, and to provide guidelines on the general
rules governing the contents. The contractor is free to use their own documentation
template.
The objective of this document is to set up o global rule for contractors to build up
their installation documents before the delivery of an installation (full installation,
patch, bug fix, ).
An inadequate, incomplete or inexistent install procedure may lead to the
refusal of the delivery.
This procedure is an obligation for contractors to provide installation instructions (see
point 3.2 Reference Document: Technical Environment Document) in order to reduce
possible manipulation mistakes, errors, misinterpretations, loss of time to find the
correct information, etc. ..., during the software installation phase for the integration
team.

1.2

Scope

This document is intended for the Publications Office software development

contractors and their team, in order to comply with general admitted rules from both
parties, concerning the use of correct, well formed, up to date, relevant and clear
install documents.
It will not cover detailed aspects such as the acceptance or validation procedures, nor
the technical environment. Should you need further and complete information about
these topics, please refer to the reference documents, mentioned in this document.

1.3

General Principles

All deliveries must be compliant to the Publications Office standard procedures

established by the Technical Environment Document (Chapter 4: Standard operating
procedures, paragraphs a Management of software releases, bug reports and change
requests and b Software deliveries), and respect the rules defined in the document.
Integrators are not experts of the application hence the need of a step-by-step
instructions on how to install.
Contractor has to made distinction between a full install and patch delivery and
installation instructions have to reflect this.
All deliveries shall contain:
-

Release Note document;

Build Procedure;
Source and Executable code;
TEST Folder;

Install Document Template

Page 3 of 10

AO 10463
Annex 20 Template for Installation Manual
Please refer to the latest version of the above mentioned document for complete
detailed information.

1.4

Quality Control

The objective of checking (testing) all deliveries is to validate all changes to the
production environment against its acceptance and validation criteria (Ref. Software
Acceptance Procedure).
The Publication Office quality improvement of the information systems will proceed
with all the deliveries to the quality check:

before installation
-

Acceptance procedure used to detect, as soon as possible, any possible

defect;
This procedure is a static testing performed before to install a new
delivery, aiming to detect any defect in the delivery as soon as possible. It
is based on an automatic inspection of files, and a visual check of the
delivery, based on the components of the delivery.
Please refer to the Software Installation Testing Procedure for further
details on this step.

after installation
-

Validation procedure used to detect defects introduced during installation

procedure.
This procedure is performed after the install of a new delivery aiming to
detect any defect introduced during the installation. It is based on an
automatic inspection of files, and different check performed to ensure the
application is up and running.
Please refer to Software Installation Testing Procedure for further details
on this step.

2 Installation Manual
In order to facilitate the integrators tasks, it is vital to provide the delivery with
accurate, exhaustive, complete and clear installation instructions.
Please note that integrators are not specialist for all the applications running at the
Publications Office, and if errors arise during the install, they are not always aware of
the actions that should be taken to correct the problem and continue the installation.
Please fill the Contact Information list at the end of this document with the names of
relevant people to contact if necessary.
The main components that should be completely and correctly described are the
following:
-

Prerequisites
Install procedure
Rollback or Un-install procedure
Tests

A Word document template (Install Document Template.dot) can be provided and is

available on request.

Install Document Template

Page 4 of 10

AO 10463
Annex 20 Template for Installation Manual

2.1

Pre-requisites

In this section a list of install prerequisites (if any) are mentioned that must be
fulfilled before the install can begin.
Prerequisites are of the order of
-

Operating System
Software Components used by the application (e.g. DataBase, Application
Software, )
System Environment Variables
Configuration Files
System Requirements (Software and/or Harware)

If the application needs that some Environment Variables to be set, please specify all
the variables to be checked and the value to which they should correspond. In case of
discrepancy please detail what actions should be undertaken by integrators, in order to
prevent errors, failures during install.
Example:
$JAVA_HOME

folder is set to /<folder/to/java>

$APPLICATION_CONF

folder is set to /<folder/to/application/configuration>

Some applications may require that some tools/applications are installed (i.e. Oracle,
JAVA, Apache, ) and a minimum version/release is required to allow the application
to run without any errors.
If this is the case, carefully list and detail the entire needed tools ant their respective
minimum version/releases.
Example:
JBoss version 4.2.3 GA server is installed
Tomcat version 6.0.18 server is installed
JAVA version 1.6.0_23

Configuration files are also a key element for the correct functioning of an
application, and can be useful to mention the key conf files that must be present and
mandatory information that must be checked, and their respective location.
The contractor is explicitly requested to mention the minimum criteria the system
should have for a particular application.

2.2

Pre-installation Tasks

Please list here any tasks that should be completed before the installation of the
software delivery is started, for example tests that should be carried out to verify that
the software defect that the delivery is supposed to correct is present.

Install Document Template

Page 5 of 10

AO 10463
Annex 20 Template for Installation Manual

2.3

Installation Procedure

Once all prerequisite checks and controls are positively finished, the install process
can start. This section must be as clear and explicit as possible listing all the steps, in
chronological order, the integrator must follow to complete the task.
Additionally clearly indicate the actor/role who has to perform the tasks: group tasks
for one group of people as much as possible (i.e. database team, systems team, ).
Distinction must be made for the following groups: this implies that these operations
should be grouped as much as possible, so the installation takes place in a linear
process, to avoid wasting time when the installation process has to jump between
different groups of people.

2.3.1

Database

Although the database tasks are part of the installation, these tasks are performed by a
different team of people.
Most database installation tasks include, but are not limited to, the following:
-

configuration modifications;
users, groups, roles and their privileges;
database creation / update;
tables creation / update;
data import / export;

These tasks should be clearly explained to avoid any possible confusion (the database
team at the Publication Office, handles a huge number of databases), in sequential
order, mentioning all the necessary information to execute the task (i.e. database
name, login info: admin, special user, user, )

2.3.2

Systems

The delivery may include tasks to be operated by the systems team (UNIX, Windows,
). Provide all necessary information to perform these operations (if any) prior
and/or during installation.
Most systems installation tasks include, but are not limited to, the following:
-

2.3.3

file system setup;

disk space, memory upgrade;
installation done by an administrator (i.e. using root user under UNIX);
users creation/modification;

Configuration

Indicate all the configuration parameter used by the application that is being installed
so it works correctly into the OP systems and environment. Please double check that
this values correspond (in terms of server names, IP addresses, folder architecture and
files locations, ) to what is existing at OP, and not to your tests environment and/or
server.
Most configuration tasks include, but are not limited to, the following:
-

properties / configuration files;

environment variables;

Install Document Template

Page 6 of 10

AO 10463
-

2.3.4

Annex 20 Template for Installation Manual

one-shot scripts;

Application Server:

BEA / TOMCAT must be compliant to the standard procedures at OP.

A special mention must be set on the backup of all elements that are being handled for
the current delivery, in order to proceed to a uninstall if necessary

2.4

Tasks Description

A good method is to describe these steps in a table in order to have a visual view of
the procedure, instead than a textual explanation of the different tasks.
Step

User

Command to execute

1.

user1

pfexec ./user1 /application/<appname>/user/system/init.d/appName stop

2.

user1

cd /applications/<appname>/users/<appuser>/setup
cp conf confYYYMMDD
or
cp
/applications/<appname>/users/<appuser>/setup/conf
/applications/<appname>/users/<appuser>/setup/confYYYMMDD

3.

User2

rm rf /applications/<appname>/users/<appuser>/setup/bin
rm rf /applications/<appname>/users/<appuser>/setup/etc
rm rf /applications/<appname>/users/<appuser>/setup/lib

4.

User1

mkdir p rf /applications/<appname>/users/appName/INSTALL/setup

5.

user1

cp
/origin/folder/delivery/delivery_file.zip
/applications/<appname>/users/appName/INSTALL/setup

6.

user1

cd /applications/<appname>/users/<appuser>/INSTALL/setup
unzip delivery_file.zip

7.

DBA

Connect to Database1

8.

DBA

Execute script:
modify_database.sql
import_data.sql

9.

DBA

10.

user1

11.

user2

Step: ordinal numbering of the steps, in chronological order

User: specify the user (e.g. UNIX login) which should execute the installation, or
execute the command.

Commands to execute: unambiguous command the integrator has to execute. It

should contain precise information upon its use (i.e. parameters)

Install Document Template

Page 7 of 10

AO 10463

Annex 20 Template for Installation Manual

Remarks (optional): any additional useful information that will clarify and/or
explain the objective of the step, expected results, additional checks, etc.

2.5

Post-installation
The installation instructions should contain a check list that details

the list of all files modified during the installation

the location of the configuration files; a list of useful parameters; if
necessary, global configuration files will be used in order to avoid multiple
definitions of the same parameters/variables
the list of periodic jobs to schedule
a procedure to check the correct installation/working of the application:
basic checks to be performed by the person in charge of the installation
should allow to check if the application is behaving correctly without
requiring a full functional validation.

2.6

Technical Tests

Adequate testing prior release to production is necessary to check not only functional
aspects of the delivery but also not-functional ones.
Contractors should include in the delivery a separate folder with all the necessary test
files, tools, scripts, , and a complete well formed test plan procedure, that can be
handled by the test team.
The test plan should be linked to the delivery package it belongs to, describe the
purpose of the tests, and should mention in an unambiguous way the correct
environment prerequisites and information, the location of the data source needed as
input (if any), the actions to perform and the expected results, the output files location
(if any).
Some tests might need to be performed before delivery install: mention of this
particular situation should be included in the test plan, in order to inform the people
concerned.
Remark:
Test must be executed at the Publications Office: contractors must keep in mind that
tests performed at their premises may differ because of a system environment, tools
version, , differences.
A comparative check between the two systems should be done before delivery in
order to avoid errors.
As an example the test plan could be formatted the following way:
[Test Case

[Test Case Title]

Description

[brief description of the test case]

Actors

[list of actors and user roles required to run the test case]

Preconditions

[constraints on the system that have to be satisfied before the test case can be executed]
for example, input or location of data source

Start

Date

Install Document Template

Page 8 of 10

AO 10463
Annex 20 Template for Installation Manual
and Time
End Date and
Time
Steps
Step 1

[action to be taken, task to be executed]

for example: Connect to server2 as user1

Step 2

From the main installation package, extract the following to an empty temporary
directory on the server2 server:
-

Step 3

Install/user1/_this_release_bin.opoce.tar

From the test folder, execute the script as follow:

./testrelease.sh input/new_files/TEST_THIS_FILE

Step 4

verify results

...
Expected
Results

[the expected outcome of the test case]

Actual
Results

[test case successful yes/no? expected result met?]

2.7

Uninstall or Roll-back

A detailed procedure how to uninstall the application should be provided that follows
the same general remarks as the installation procedure.
The rollback procedure must be as clear and explicit as the install procedure, as it
must allow undoing all changes to the situation before the installation has been
performed.
The same rules apply concerning the steps to execute to re-establish the old
application delivery.
As an example the same format and method used for the install procedure can be
followed to describe the rollback.

3 Additional Information
3.1

Acronyms, Abbreviations

Value

Definition

{$VARIABLE}

Variable used in this document.

<appname>

name of the application

<appuser>

user identification of the user running the application

3.2

Reference Documents

Title

Description

Technical Environment Document

Technical Environment and Standard Operating

Procedures of the Publications Office

Install Document Template

Page 9 of 10

AO 10463
Annex 20 Template for Installation Manual
Software Installation Testing Procedure

procedure describing the tests executed during the

pre-installation acceptance and post-installation
validation phases

Software Acceptance Procedure

procedure that formalises the processing of

installation requests and sets the rules that govern the
acceptance of a software delivery

3.3

Contact Information

Title

Description

DL OPOCE INFRA INT TEST

Integrator team who performs the installation at the

Publication Office

<.>

Contractor Technical contact

<.>

Contractor Project Manager

<.>

Additional contacts may be added here

Install Document Template

Page 10 of 10